home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / RCS / Fs_Dispatch.man,v < prev    next >
Text File  |  1989-01-27  |  6KB  |  209 lines
  1. head     1.3;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.3
  10. date     89.01.27.08.37.01;  author ouster;  state Exp;
  11. branches ;
  12. next     1.2;
  13.  
  14. 1.2
  15. date     89.01.26.10.05.19;  author ouster;  state Exp;
  16. branches ;
  17. next     1.1;
  18.  
  19. 1.1
  20. date     89.01.26.10.01.12;  author ouster;  state Exp;
  21. branches ;
  22. next     ;
  23.  
  24.  
  25. desc
  26. @@
  27.  
  28.  
  29. 1.3
  30. log
  31. @Cleanup comment sequences.
  32. @
  33. text
  34. @'\" Copyright 1989 Regents of the University of California
  35. '\" Permission to use, copy, modify, and distribute this
  36. '\" documentation for any purpose and without fee is hereby
  37. '\" granted, provided that this notice appears in all copies.
  38. '\" The University of California makes no representations about
  39. '\" the suitability of this material for any purpose.  It is
  40. '\" provided "as is" without express or implied warranty.
  41. '\" 
  42. '\" $Header: /sprite/src/lib/c/etc/RCS/Fs_Dispatch.man,v 1.2 89/01/26 10:05:19 ouster Exp $ SPRITE (Berkeley)
  43. '\" 
  44. .so \*(]ltmac.sprite
  45. .HS Fs_Dispatch lib
  46. .BS
  47. .SH NAME
  48. Fs_Dispatch, Fs_EventHandlerCreate, Fs_EventHandlerDestroy, Fs_EventHandlerData,
  49. Fs_EventHandlerChangeData, Fs_TimeoutHandlerCreate, Fs_TimeoutHandlerDestroy \- stream event and timeout dispatcher routines.
  50. .SH SYNOPSIS
  51. .nf
  52. \fB#include <fs.h>\fR
  53.  
  54. void 
  55. \fBFs_Dispatch\fR()
  56.  
  57. void 
  58. \fBFs_EventHandlerCreate\fR(\fIstreamID, eventMask, proc, clientData\fP)
  59.  
  60. void 
  61. \fBFs_EventHandlerDestroy\fR(\fIstreamID\fP)
  62.  
  63. void 
  64. \fBFs_EventHandlerData\fR(\fIstreamID\fP)
  65.  
  66. ClientData 
  67. \fBFs_EventHandlerChangeData\fR(\fIstreamID, clientData\fP)
  68.  
  69. \fB#include <time.h>\fR
  70.  
  71. Fs_TimeoutHandler 
  72. \fBFs_TimeoutHandlerCreate\fR(\fItime, relativeTime, proc, clientData\fP)
  73.  
  74. void 
  75. \fBFs_TimeoutHandlerDestroy\fR(\fPtoken\fP)
  76.  
  77. .SH ARGUMENTS
  78. .AS Fs_TimeoutHandler relativeTime
  79. .AP int streamID in
  80. Specifies the stream to create an event handler for.
  81. .AP int eventMask in
  82. Mask indicating which events on \fIstreamID\fP are to be processed 
  83. by \fIproc\fP. Can be the bitwise OR of \fBFS_READABLE\fR, \fBFS_WRITABLE\fR and
  84. \fBFS_EXCEPTION\fR.
  85. .AP void (*proc)() in
  86. Procedure to invoke when one of the events in \fIeventMask\fP occurs on a 
  87. stream or when a timeout period expires.
  88. .AP ClientData clientData in
  89. Uninterpreted value passed to \fIproc\fP when it is invoked.
  90. .AP Time time in
  91. The absolute time when \fIproc\fP should be called or the time interval
  92. between calls to \fIproc\fP.
  93. .AP Boolean relativeTime in
  94. If \fBTRUE\fR, then \fItime\fP specifies a interval between calls to \fIproc\fP.
  95. If \fBFALSE\fR, then \fItime\fP specifies the absolute time when \fIproc\fP should
  96. be called.
  97. .AP Fs_TimeoutHandler token in
  98. A token to identify a particular timeout handler so it can be destroyed.
  99. .BE
  100. .SH DESCRIPTION
  101. These routines implement a dispatcher for events on streams and
  102. timeouts. An event occurs when the stream becomes readable, writable or
  103. has an exception condition pending. The dispatcher handles the 
  104. details of waiting for events to
  105. occur on streams. When an event occurs, the dispatcher calls a routine
  106. supplied by the clients to deal with the event. Also, timeout handlers can
  107. be created so that a client-supplied routine can be called at a
  108. specific time or at regular intervals.
  109. .PP
  110. The dispatcher must be initialized by calling \fBFs_EventHandlerCreate\fR and/or
  111. \fBFs_TimeoutHandlerCreate\fR before \fBFs_Dispatch\fR is called.
  112. \fBFs_Dispatch\fR causes the process to wait until an event occurs on a stream 
  113. or until a time-out occurs. 
  114. At that point, it calls the appropriate handler. Once the handler completes,
  115. \fBFs_Dispatch\fR returns to its caller. To have the dispatcher remain in control,
  116. do
  117. .DS
  118.     while (TRUE) {
  119.     Fs_Dispatch();
  120.     }
  121. .DE
  122. .PP
  123. \fBFs_EventHandlerCreate\fR is used to cause the procedure \fIproc\fP to be 
  124. called when one or more of the events in \fIeventMask\fP occur 
  125. on \fIstreamID\fP. Only one procedure may be attached to a stream so 
  126. it should be able to deal with all of the event types. 
  127. \fIProc\fP should be declared as:
  128. .DS
  129. void
  130. proc(clientData, streamID, eventMask)
  131.     ClientData    clientData;
  132.     int        streamID;
  133.     int        eventMask;
  134. { 
  135. }
  136. .DE
  137. \fBFs_EventHandlerData\fR can be used to get the \fIclientData\fP associated with
  138. \fIstreamID\fP. 
  139. \fBFs_EventHandlerChangeData\fR can be used to change the \fIclientData\fP 
  140. associated with \fIstreamID\fP. 
  141. The handler can be destroyed with \fBFs_EventHandlerDestroy\fR.
  142. .PP
  143. In addition, a time-out routine can be setup to be called using
  144. \fBFs_TimeoutHandlerCreate\fR. If \fIrelativeTime\fP is \fBTRUE\fR, then \fItime\fP 
  145. specifies an interval (e.g. one hour) 
  146. from the current time that \fIproc\fP will be called at.
  147. When \fIproc\fP returns, it will automatically be rescheduled to be called 
  148. at the next interval. If \fIproc\fP doesn't need to be called again, it should
  149. call \fBFs_TimeoutHandlerDestroy\fR.
  150. If \fIrelativeTime\fP is \fBFALSE\fR, then \fItime\fP specifies a specific time
  151. (e.g., 3:15pm 17 Sept. 1987)
  152. that \fIproc\fP will be called at. \fIProc\fP is called once \(em it is not
  153. automatically rescheduled to be called again. However, it could call
  154. \fBFs_TimeoutHandlerCreate\fR to cause it to be called again.
  155. \fIProc\fP should be declared as:
  156. .DS
  157. void
  158. proc(clientData, time)
  159.     ClientData    clientData;
  160.     Time    Time;
  161. { 
  162. }
  163. .DE
  164. For example, to have \fBExampleRoutine\fR called in 1 minute from now and every
  165. minute after that, the call should be:
  166. .DS
  167.   Fs_TimeoutHandlerCreate(time_OneMinute, TRUE, ExampleRoutine, clientData);
  168. .DE
  169. \fBFs_TimeoutHandlerCreate\fR returns a token that must be saved 
  170. if \fBFs_TimeoutHandlerDestroy\fR is to be called.
  171.  
  172. .SH KEYWORDS
  173. callback, client data, dispatcher, stream ID, time
  174. @
  175.  
  176.  
  177. 1.2
  178. log
  179. @Typo.
  180. @
  181. text
  182. @d1 10
  183. a10 10
  184. ' Copyright 1989 Regents of the University of California
  185. ' Permission to use, copy, modify, and distribute this
  186. ' documentation for any purpose and without fee is hereby
  187. ' granted, provided that this notice appears in all copies.
  188. ' The University of California makes no representations about
  189. ' the suitability of this material for any purpose.  It is
  190. ' provided "as is" without express or implied warranty.
  191. ' 
  192. ' $Header: /sprite/src/lib/c/etc/RCS/Fs_Dispatch.man,v 1.1 89/01/26 10:01:12 ouster Exp Locker: ouster $ SPRITE (Berkeley)
  193. ' 
  194. @
  195.  
  196.  
  197. 1.1
  198. log
  199. @Initial revision
  200. @
  201. text
  202. @d9 1
  203. a9 1
  204. ' $Header: /sprite/lib/forms/RCS/proto.man,v 1.3 89/01/09 11:43:01 ouster Exp $ SPRITE (Berkeley)
  205. d12 1
  206. a12 1
  207. .HS Fs_Dispatch libc
  208. @
  209.